Skip to main content

Get Master Locations

Method: GET
/locations

As a Customer of iFoodDS, you can use the Get Master Locations API to query master locations from the iFoodDS Trace Exchange platform. The recommended query parameters support location onboarding, master data management, trading partner setup, FSMA 204 compliance workflows, and supply chain mapping.

info

This endpoint is being refined and thus subject to change. The query parameters below describe the recommended filter set; availability may depend on implementation phase. These docs will update when changes are made.

Request​

Type: application/json

Retrieving master locations via the API is done through paging. Supply optional query parameters in the request URL to select a page and filter the locations returned.

Query Parameters​

All query parameters are optional. Applicable search parameters support comma-separated lists as described below.

Pagination & Dates​

  • page (number): The page index of the locations to return. The first page is index 0.
  • size (number): The number of results to return per page. Default value is 20.
  • submitStartDateTime (datetime): Filters results to include only locations submitted after the specified date and time.
  • submitEndDateTime (datetime): Filters results to include only locations submitted before the specified date and time.

Location Identification​

  • id (uuid): Filters by the unique location identifier. Supports comma-separated UUIDs.
  • gln (string): Filters by the Global Location Number. Supports comma-separated values.
  • duns (string): Filters by the Data Universal Numbering System identifier. Supports comma-separated values.
  • locationCode (string): Filters by the location code. Supports comma-separated values.
  • alternateLocationId (string): Filters by the alternate location identifier. Supports comma-separated values.
  • parentLocationId (string): Filters by the parent location identifier to find child locations. Supports comma-separated values.

Location Information​

  • locationName (string): Filters by the location name. Supports comma-separated values.
  • locationType (string): Filters by the location type, such as Supplier or Internal. Supports comma-separated values.
  • businessUnit (string): Filters by the business unit associated with a location. Supports comma-separated values.

Geography​

  • country (string): Filters by the country where a location is situated. Supports comma-separated values.
  • state (string): Filters by the state or province where a location is situated. Supports comma-separated values.
  • city (string): Filters by the city where a location is situated. Supports comma-separated values.
  • postalCode (string): Filters by the postal or ZIP code. Supports comma-separated values.

Regulatory & Hierarchy​

  • isCoveredByGdst (boolean): Filters by whether a location is covered by GDST. Use true or false.
  • isPrimaryLocation (boolean): Filters by whether a location is a primary location. Use true or false.
  • glnAssignedBy (string): Filters by the organization that assigned the GLN. Supports comma-separated values.

Multi-Value Support​

For the identification, location information, geography, and glnAssignedBy filters, pass multiple values as a comma-separated list in a single query parameter. Separate different query parameters with &.

Multiple location codes
/locations?locationCode=DC001,DC002
Multiple GLNs
/locations?gln=1234567890123,9876543210987
Multiple location types
/locations?locationType=Supplier,Internal
Multiple states
/locations?state=NC,VA

Request Examples​

Find location DC001
/locations?locationCode=DC001
Find locations in North Carolina
/locations?state=NC
Find a location by GLN
/locations?gln=1234567890123
Find locations belonging to a business unit
/locations?businessUnit=Produce
Find GDST-covered facilities
/locations?isCoveredByGdst=true

To find all distribution centers, use locationType with the value used to classify distribution centers in your location master data.

Implementation Priorities​

If implementation is phased, prioritize these 10 filters to cover the majority of onboarding, integration, and traceability requests:

  1. locationCode
  2. gln
  3. locationName
  4. locationType
  5. country
  6. state
  7. city
  8. businessUnit
  9. isCoveredByGdst
  10. parentLocationId

Data Constraints​

  • datetimes must use the format: yyyy-MM-ddTHH:mm:ss.
  • Pagination, date, and boolean parameters accept a single value.
  • URL-encode special characters in query values, such as spaces in location names or business units.

Response​

Return result for the master locations queried.

{
    "content": [
        {
            "id": "<location id>",
            "gln": "<global location number>",
            "city": "<city>",
            "duns": "<duns number>",
            "state": "<state>",
            "country": "<country>",
            "geoFence": "<geo fence coordinates>",
            "postalCode": "<postal code>",
            "phoneNumber": "<phone number>",
            "businessUnit": "<business unit>",
            "locationCode": "<location code>",
            "locationName": "<location name>",
            "locationType": "<location type>",
            "glnAssignedBy": "<gln assigned by>",
            "gpsCoordinates": "<gps coordinates>",
            "streetAddress1": "<street address 1>",
            "streetAddress2": "<street address 2>",
            "isCoveredByGdst": <is covered by gdst>,
            "parentLocationId": "<parent location id>",
            "isPrimaryLocation": <is primary location>,
            "alternateLocationId": "<alternate location id>"
        }
    ],
    "pageable": {
        "pageNumber": <page number>,
        "pageSize": <page size>,
        "sort": {
            "unsorted": <is unsorted>,
            "sorted": <is sorted>,
            "empty": <is page empty>
        },
        "offset": <offset size>,
        "unpaged": <is unpaged>,
        "paged": <is paged>
    },
    "totalPages": <total pages>,
    "totalElements": <total elements>,
    "last": <is last page>,
    "numberOfElements": <number of elements>,
    "size": <page size>,
    "number": <page number>,
    "sort": {
        "unsorted": <is unsorted>,
        "sorted": <is sorted>,
        "empty": <is empty>
    },
    "first": <is first page>,
    "empty": <is page empty>
}

Content​

  • id (uuid): The unique identifier for the location
  • gln (string): GS1 Global Location Number, a 13-digit string. GS1 GTIN Executive Summary
  • city (string): The city where the location is situated
  • duns (string): Data Universal Numbering System identifier
  • state (string): The state or province where the location is situated
  • country (string): The country where the location is situated
  • geoFence (string): A series of GPS coordinates that define the boundaries of the location
  • postalCode (string): The postal or ZIP code for the location
  • phoneNumber (string): Contact phone number for the location
  • businessUnit (string): The business unit associated with this location
  • locationCode (string): A unique code identifier for the location
  • locationName (string): The name of the location
  • locationType (string): The type of location
  • glnAssignedBy (string): The organization that assigned the GLN
  • gpsCoordinates (string): The GPS coordinates for the location
  • streetAddress1 (string): The primary street address
  • streetAddress2 (string): Additional address information (e.g., suite number)
  • isCoveredByGdst (boolean): Indicate if the location is part of GDST
  • parentLocationId (string): Identifier for the parent location, if this is a child location
  • isPrimaryLocation (boolean): Indicates if this is the primary location
  • alternateLocationId (string): Alternate ID of the location

Pageable​

  • pageable (object)
    • pageNumber (number): The current page number in the page series. Index 0 is first page
    • pageSize (number): The number of events contained in the page
    • offset (number): If there is an offset specified on there return results this will be populates. Default is 0
    • unpaged (boolean): If the record set is unpaged then true else false
    • paged (boolean): If the record set is paged then true else false
    • sort (object)
      • unsorted (boolean): If the record set is unsorted then true else false
      • sorted (boolean): If the record set is sorted then true else false
      • empty (boolean): If the record set is empty then true else false
  • totalPages (number): The total amount of pages that contain all events in the query
  • totalElements (number): The total amount of events in the query
  • last (boolean): If the page is the last in the series then true else false
  • numberOfElements (number): The total amount of events in the table
  • size (number): The number of events contained in the page
  • number (number): The current page number in the page series
  • sort (object)
    • unsorted (boolean): If the record set is unsorted then true else false
    • sorted (boolean): If the record set is sorted then true else false
    • empty (boolean): If the record set is empty then true else false
  • first (boolean): If the page is the first in the series then true else false
  • empty (boolean): If the page is empty then true else false

Sample Response​

{
  "content": [
    {
      "id": "d96583b3-8cf9-43bb-9db3-02f060bb4a53",
      "gln": "1234567890123",
      "city": "Springfield",
      "duns": "123456789",
      "state": "IL",
      "country": "US",
      "geoFence": "40.28,-84.15,40.29,-84.14,40.27,-84.14",
      "postalCode": "62701",
      "phoneNumber": "+1-800-555-0199",
      "businessUnit": null,
      "locationCode": "CDC001",
      "locationName": "Central Distribution Center",
      "locationType": "Internal",
      "glnAssignedBy": "GS1",
      "gpsCoordinates": "86.271142,-79.593557",
      "streetAddress1": "123 Main St",
      "streetAddress2": "Suite 100",
      "isCoveredByGdst": false,
      "parentLocationId": "HQ001",
      "isPrimaryLocation": true,
      "alternateLocationId": null
    }
  ],
  "pageable": {
    "pageNumber": 0,
    "pageSize": 20,
    "sort": {
      "unsorted": true,
      "sorted": false,
      "empty": true
    },
    "offset": 0,
    "unpaged": false,
    "paged": true
  },
  "totalPages": 22,
  "totalElements": 440,
  "last": false,
  "numberOfElements": 20,
  "size": 20,
  "number": 0,
  "sort": {
    "unsorted": true,
    "sorted": false,
    "empty": true
  },
  "first": true,
  "empty": false
}